/*
 * Copyright 2012 The Netty Project
 *
 * The Netty Project licenses this file to you under the Apache License,
 * version 2.0 (the "License"); you may not use this file except in compliance
 * with the License. You may obtain a copy of the License at:
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations
 * under the License.
 */
package io.netty.channel;

import io.netty.bootstrap.Bootstrap;
import io.netty.util.concurrent.BlockingOperationException;
import io.netty.util.concurrent.Future;
import io.netty.util.concurrent.GenericFutureListener;

import java.util.concurrent.TimeUnit;


/**
 *
 * 该类是channel IO异步操作结果的抽象
 *
 * <p>
 * All I/O operations in Netty are asynchronous.  It means any I/O calls will
 * return immediately with no guarantee that the requested I/O operation has
 * been completed at the end of the call.  Instead, you will be returned with
 * a {@link ChannelFuture} instance which gives you the information about the
 * result or status of the I/O operation.
 * <p>
 *
 * 在netty中所有的IO操作都是异步的。这意味这所有的IO调用都会立即返回，且不保证IO操作完成。
 * IO调用会返回一个ChannelFuture的实例，通过该实例可以活动IO操作的结果和状态
 *
 *
 *ChannelFuture有完成和未完成两种状态， 当IO操作开始，就会创建一个ChannelFuture的实例，该实例初始是未完成状态
 * 它不是成功，失败，或者取消，应为IO操作还没有完成，如果IO操作完成了那么将会有成功，失败，和取消状态，
 *
 * 注意：成功，失败，和取消都属于完成状态。完成状态的ChannelFuture实例携带了很多特定信息，比如导致失败的原因。
 *
 * <pre>
 *                                      +---------------------------+
 *                                      | Completed successfully    |
 *                                      +---------------------------+
 *                                 +---->      isDone() = <b>true</b>      |
 * +--------------------------+    |    |   isSuccess() = <b>true</b>      |
 * |        Uncompleted       |    |    +===========================+
 * +--------------------------+    |    | Completed with failure    |
 * |      isDone() = <b>false</b>    |    |    +---------------------------+
 * |   isSuccess() = false    |----+---->   isDone() = <b>true</b>         |
 * | isCancelled() = false    |    |    | cause() = <b>non-null</b>     |
 * |    cause() = null     |    |    +===========================+
 * +--------------------------+    |    | Completed by cancellation |
 *                                 |    +---------------------------+
 *                                 +---->      isDone() = <b>true</b>      |
 *                                      | isCancelled() = <b>true</b>      |
 *                                      +---------------------------+
 * </pre>
 *
 *
 * 该类提供了很多方法用来检查IO操作是否完成，等待完成，和接受IO操作的结果。还可以添加ChannelFutureListener的监听器
 * 这样IO操作完成时就可以得到提醒
 *
 * 强烈建议使用addListener而不是await。
 *
 * addListener是非阻塞的，它简单的添加指定的ChannelFutureListener到ChannelFuture中，
 * IO线程将在当绑定在这个future的IO操作完成时，触发这个触发器，优点是提高效率和资源的利用率
 *
 * await()是一个阻塞方法，一旦调用，调用线程将会阻塞直到IO操作完成。优点是容易实现顺序逻辑
 *
 */
public interface ChannelFuture extends Future<Void> {

    /**
     * Returns a channel where the I/O operation associated with this
     * future takes place.
     */
    Channel channel();

    @Override
    ChannelFuture addListener(GenericFutureListener<? extends Future<? super Void>> listener);

    @Override
    ChannelFuture addListeners(GenericFutureListener<? extends Future<? super Void>>... listeners);

    @Override
    ChannelFuture removeListener(GenericFutureListener<? extends Future<? super Void>> listener);

    @Override
    ChannelFuture removeListeners(GenericFutureListener<? extends Future<? super Void>>... listeners);

    @Override
    ChannelFuture sync() throws InterruptedException;

    @Override
    ChannelFuture syncUninterruptibly();

    @Override
    ChannelFuture await() throws InterruptedException;

    @Override
    ChannelFuture awaitUninterruptibly();
}
